What is the Rules Engine?

The Rules Engine is a high-performance targeting system that enables real-time content personalization and campaign management through sophisticated rule evaluation. It uses WebSocket technology to provide ultra-fast context evaluation (77x faster than REST) and delivers personalized content based on complex rule sets.

Core Concepts

Context Objects

A context object represents the current state that the Rules Engine will evaluate against. It contains three main sections that rules can target:

1. Moment: Represents the current point in time for rules evaluation

   • start: Current timestamp in milliseconds
   • duration: Time window for rule validity
   • Example use case: Rules that trigger during specific scenes in a video or time periods in a live event

2. Environment: Contains situational data for rule evaluation

   • Device information (mobile/desktop, browser type)
   • User demographics and location
   • Weather conditions
   • Time of day/date
   • Media information (what they're watching/listening to)
   • Example use case: Rules targeting mobile users in cold weather with hot beverage ads

3. Metadata: Additional rule evaluation criteria

   • Keywords detected in the content
   • IAB categories present
   • Example use case: Rules triggering on sports-related content when sports keywords are detected

Rules & Strategies

The Rules Engine uses strategies as containers for business rules. Each strategy contains:

1. Conditions: Rule definitions that determine content targeting

   • Can be simple matches or complex logical operations
   • Uses JSON Logic for powerful rule creation
   • Example:

     {
       "type": "json-logic",
       "id": "weather-rule",
       "rule": {
         "and": [
           {"==": [{"var": "environment.weather.condition"}, "raining"]},
           {">": [{"var": "environment.weather.temperature"}, 70]}
         ]
       }
     }

2. Effects: Actions triggered when rules match

   • Content to display
   • Timing information
   • Presentation details
   • Example:

     {
       "type": "content",
       "id": "rainy-day-ad",
       "on": "weather-rule",
       "content": [{
         "type": "activation",
         "id": "umbrella-promotion",
         "instance": {
           "text": "Stay dry with our premium umbrellas!",
           "start": 1000,
           "duration": 10000
         }
       }]
     }

Implementation Guide

Connection Methods

WebSocket (Recommended)

The Rules Engine provides a WebSocket interface for real-time rule evaluation:

const ws = new WebSocket('wss://your-rules-engine-url');

ws.onopen = () => {
  console.log('Connected to Rules Engine');
  
  // Send context for evaluation
  const context = {
    moment: {
      start: Date.now(),
      duration: 10000
    },
    environment: {
      device: {
        type: 'mobile',
        os: 'ios',
        browser: 'safari'
      },
      // ... other environment data
    },
    metadata: {
      keywords: [/* ... */],
      categories: {
        iab: [/* ... */]
      }
    }
  };
  
  ws.send(JSON.stringify(context));
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  // Handle matching rules and their effects
  result.effects.forEach(effect => {
    handleEffect(effect);
  });
};

HTTP (Alternative)

For systems that can't use WebSockets, an HTTP interface is available:

async function evaluateRules(context) {
  const response = await fetch('https://your-rules-engine-url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(context)
  });
  
  return response.json();
}

Rule Creation Best Practices

1. Granular Rules

   • Create specific, focused rules for better maintainability
   • Combine rules using JSON Logic for complex scenarios
   • Example: Separate weather and time-of-day rules that can be combined

2. Performance Optimization

   • Order conditions from most to least likely to fail
   • Use appropriate time windows in moment objects
   • Cache context objects when possible

3. Testing Rules

   • Use the Rules Engine playground for testing
   • Create test contexts covering edge cases
   • Verify rule combinations work as expected

Advanced Features

Rule Chaining

Rules can trigger other rules using the on field:

{
  "type": "json-logic",
  "id": "primary-rule",
  "rule": {
    "==": [{"var": "environment.weather.condition"}, "sunny"]
  }
}

{
  "type": "json-logic",
  "id": "secondary-rule",
  "on": "primary-rule",
  "rule": {
    ">": [{"var": "environment.temperature"}, 80]
  }
}

Multi-Condition Rules

Combine multiple conditions for sophisticated targeting:

{
  "type": "json-logic",
  "id": "complex-rule",
  "rule": {
    "and": [
      {
        "or": [
          {"==": [{"var": "environment.device.type"}, "mobile"]},
          {"==": [{"var": "environment.device.type"}, "tablet"]}
        ]
      },
      {
        ">=": [{"var": "environment.user.age"}, 18]
      },
      {
        "in": [
          {"var": "environment.time.dayName"},
          ["saturday", "sunday"]
        ]
      }
    ]
  }
}

Real-time Updates

The Rules Engine supports live rule updates without service restart:

1. Rules are synchronized in real-time
2. Changes take effect immediately
3. No service interruption required

Monetization Features

Value Attribution

Each rule can include monetization parameters:

{
  "type": "content",
  "id": "premium-ad",
  "strategy": {
    "id": "summer-campaign",
    "value": {
      "impression": 0.0015,
      "engagement": 0.01,
      "action": 0.05
    }
  }
}

Performance Tracking

Track rule performance with built-in metrics:

• Impression rates
• Engagement rates
• Conversion rates
• Rule triggering frequency

Administration

Rule Management

Access the admin interface at http://your-rules-engine-url/admin to:

1. Create and edit rules
2. Monitor rule performance
3. View active connections
4. Send test contexts

Monitoring

Monitor system health and performance:

1. WebSocket connection status
2. Rule evaluation timing
3. Error rates
4. System uptime

Security Considerations

1. Authentication

   • Use secure WebSocket connections (WSS)
   • Implement proper API key management
   • Follow least privilege principles

2. Data Privacy

   • Only send necessary context data
   • Follow data protection regulations
   • Implement data retention policies

3. Rate Limiting

   • Monitor connection frequency
   • Implement appropriate timeouts
   • Handle backpressure appropriately

Support and Troubleshooting

Common Issues

1. Connection Problems

   • Verify WebSocket URL
   • Check network connectivity
   • Confirm SSL certificate validity

2. Rule Evaluation Issues

   • Validate context object format
   • Check rule syntax
   • Review rule logic

3. Performance Problems

   • Monitor context object size
   • Review rule complexity
   • Check network latency

Getting Help

1. Review this documentation
2. Check example implementations
3. Contact support with specific issues